蓝海活动

文档说明

阅读对象

1、本规范的使用对象为服务商的技术开发人员、产品及业务。
2、开发人员应该对post提交、json 格式、http/https传输、非对称秘钥和数据签名等有一定认识。

修订记录

2019-05-06：新增

相关术语

蓝海活动：支付宝推出的针对餐饮商户优惠费率的活动。
子渠道号：通过汇付申请的渠道商/代理商自己的微信渠道号。

接口规则

协议规则

1、接口调用方式为http post。
2、数据传输使用json格式，编码使用utf-8，请求时存放json串的参数名为: jsonData，接口传递中文或含有特殊字符的参数时应URL Encoding，接口接收返回参数时应做URL Decoding。
3、如果json请求串中值为null，则json串格式应为{“test”: “”}。
4、接口的除merPriv字段之外，其他所有字段不应该包含特殊字符，如：“&”、”?”和”‘’”等。
5、后台通知商户返回应答参数的规则：为了表示商户交易系统已经收到交易应答，商户必须在应答接收页面输出一段特殊的字符串，组成规则为：固定字符串RECV_ORD_ID_加上交易应答中某一指定字段，指定字段请见具体接口商户应答参数。

安全规范

1、为了保证数据传输过程中的数据真实性和完整性，我们需要对数据进行数字签名，在接收签名数据之后进行签名校验。
2、详情请参见接口参数checkValue参数说明。
3、checkValue生成规则：目前仅支持CFCA签名方式，checkValue生成方法请参考CFCA签名。
简单示例：
HashMap<String , String> jsonDataMap = new HashMap<String , String>();
jsonDataMap.put("termOrdId" , "20180820020626985855");
jsonDataMap.put("memberId" , memberId);
jsonDataMap.put("ordAmt" , ordAmt);
jsonDataMap.put("authCode" , "134755413751742262");//二维码
jsonDataMap.put("goodsDesc" , URLEncoder.encode(goodsDesc , Constant.CHARSET_UTF8));
jsonDataMap.put("merPriv" , "{\"Ic\":\"2253425259\",\"merNoticeUrl\":\"http://172.31.13.182:38087/site/testHttp/testB/\",\"callType\":\"04\"}");
jsonDataMap.put("apiVersion" , apiVersion);

String jsonData = JSON.toJSONString(jsonDataMap);

// CFCA 签名
String checkValue = CFCASignature.signature("100001.pfx","888888", jsonData, "UTF-8").getSign();

蓝海活动

场景介绍

服务商可为旗下商户报名参加支付宝餐饮优惠费率活动。

功能描述

为商户报名支付宝餐饮优惠费率活动，报名成功后可享受千二费率。

业务流程

服务商渠道下参加活动：
1、服务商与支付宝签订蓝海协议。
2、告知汇付运营支付宝渠道相关信息，运营协助配置。
3、商户进件。
4、调用活动配置接口报名支付宝餐饮优惠活动。
5、异步通知接收报名结果。
6、商户以优惠费率进行交易。
汇付渠道下参加活动：
1、商户进件。
2、调用活动配置接口报名支付宝餐饮优惠活动。
3、异步通知接收报名结果。
4、商户以优惠费率进行交易。

API列表

活动配置接口

发布路径

https://nspos.chinapnr.com/nsposmweb/webB1433

输入参数

输入参数

参数代码

参数名称

数据类型

是否必填

参数说明

checkValue

加签密文

String

必填

Cfca方式验签

jsonData

json

json

必填

jsonData数据，内容见下方描述

JsonData

参数代码

参数名称

数据类型

是否必填

参数说明

apiVersion

接口版本号

String（7）

必填

2.0.0.2，小于7位

agentId

代理商会员号

String（18）

必填

必填，代理商会员号18位

memberId

商户号

String（18）

必填

必填，会员号

activityType

参加活动类型

String（2）

必填
枚举值
01-表示支付宝优惠活动
02-微信优惠活动
06-微信校园0费率
07-教育食堂行业活动
08-线下教培机构

archFlph20
主流餐饮平台
入驻照片

String（60）

条件必填
参加餐饮特惠时必传，支
支持修改

archFlph15

店铺门头照片

String（60）

条件必填
参加餐饮特惠时必传、教育食堂行业、线下教培时 必传
支持修改

archFlph16

店铺收银台照片

String（60）

条件必填

参加餐饮特惠时必传，支持修改

archFlph17

店内照片

String（60）

条件必填
参加餐饮特惠时必传、教育食堂行业时 必传

|支持修改

archFlph01

营业执照图片

String（60）

条件必填

参加餐饮特惠时必传，支持修改

bgRetUrl

异步通知地址

String（120）

必填

结果异步通知推送地址

reqSerialNum

请求流水号

String(120)

必填

由接入方生成且保证唯一

feeRate

手续费费率

String（10）

非必填
0.55代表费率0.55%

bankChannelNo

子渠道号

String（50）

非必填
报名餐饮活动时传入，若未传入则
取代理商绑定的子渠道号

shopStreet

门店街道名称

String（400）

条件必填
微信智慧餐饮活动必填，其他活动不用填写。
例如：XX省XX市XX县XX区XX路XX号

shopAddCode

门店区县编码

String（6）

条件必填
微信智慧餐饮活动必填，参考《智能收单
商户入驻申请接口文档-附录》区县代码，
其他活动不用填写例如370704，代表区县地址
为山东省潍坊市坊子区

archFlph33

机构资质证明照片

String（60）

条件必填
支持Zip压缩文件，如果是线下教培活动，
传机构资质证明（教育部门的批文或办学，
许可证或承诺函）。如果是教育食堂行业活动，
传学校资质证明。详细说明见微信官方文档
https://docs.qq.com/sheet/DSkZxWVhnUlFpbndy?tab=BB08J2

archFlph34

门店租赁相关证明照片

String（60）

条件必填
支持Zip压缩文件，如果是线下教培活动
传线下门店的房屋租赁合同或消防证；

archFlph35

办学许可证

String（60）

条件必填
如果是教育食堂行业活动，且主体是党政，
机关及企事业单位/其他组织，传办学许可证

archFlph36

合作资质证明照片

String（60）

条件必填
如果是教育食堂行业活动，且主体是
企业/个体户，传合作资质证明

archFlph37

优惠费率承诺函图片

String（60）

条件必填
如果是教育食堂行业活动，且主体
是企业/个体户，传优惠费率承诺函

subsidyFeeRate

补贴费率

String（10）

条件必填

用于教培商户误入驻线下扫码后补报名08活动的场景

输出参数

输出参数

参数代码

参数名称

数据类型

是否必填

参数说明

respCode

返回码

String

必填
00000成功（表示受理成功，结果以异步通知为准）
其他均为失败

respDesc

返回描述

String

非必填

返回描述

活动配置接口异步通知

发布路径

活动配置接口中传入的bgRetUrl

汇付输出参数

参数代码

参数名称

数据类型

是否必填

参数说明

respCode

返回码

String(6)

必填

000000成功,其他均为失败

respDesc

返回文字说明

String(256)

非必填

开通失败，需要告知开通失败的具体原因

checkValue

加签密文

String

必填

必填 sha256加签

jsonData

json

json

必填

jsonData数据，内容见下方描述

JsonData

参数代码

参数名称

数据类型

是否必填

参数说明

reqSerialNum

请求流水号

String（120）

必填

原样返回(由接入方生成且保证唯一)

orderId

活动订单号

String(16)

必填

汇付返回的活动订单号，每个活动全局唯一

memberId

NSPOS商户号

String（18）

必填

固定18位 ,汇付分配的商户号

agentId

代理商会员号

String（18）

必填

代理商会员号

smId

真实二级商

String（60）

选填

真实二级商户号

商户应答参数

参数代码

参数名称

数据类型

是否必填

参数说明

reqSerialNum

请求流水号

String(120)

必填

RECV_ORD_ID_{ reqSerialNum }

错误码

错误码

常见错误码描述，如还未解决问题请及时联系专业技术支持人员。
错误码 描述                               错误码 描述                                       错误码 描述
000000 操作成功                            000098 请求参数非法                               000267 接口获取状态与订单状态不符
000093 请求参数不规范                       000097 数据库异常                                000268 二维码反向交易超时
000094 重复交易                            000234 订单生成失败                               000272 订单查询，未查询到记录
000095 验签失败                            000236 PA入账失败                                 000273 支付通道类型不为微信或者支付宝
000100 业务系统已关闭                       000238 对象属性复制异常                           000277 无此交易类型
000107 业务系统不存在                       000240 冻结账务对象不存在，分账串解析为空           000278 无此交易记录
000202 订单已存在                          000241 订单被风控拒绝,风控未通过                   000279 退货失败，该笔订单非退货交易
000203 原订单不存在                        000242 风控系统调用异常                            000197 控台系统异常，网络繁忙
000204 撤销金额与原订单金额不一致           000243 撤销或退货失败，PA冻结超时                   000281 交易处理中
000205 撤销日期与原订单日期不一致           000244 不存在该账务类型                             000099 网络繁忙，请稍后再试
000206 撤销失败，账务状态异常              000245 分账串异常                                   000219 订单校验失败
000207 撤销失败，PA冻结失败                000250 退货失败，PA退款失败                          000220 签名上送失败，订单未完成支付
000208 撤销失败，通道失败                  000256 退货失败，PA冻结超时                          000221 签名上传失败，已上传
000209 撤销失败，原订单未完成              000255 确认交易失败,账务状态异常                      000213 退货失败，超出退货期限
000210 退货失败，原订单未完成              000257 确认交易失败，原订单未成功                     000214 退货失败，PA冻结失败
000211 退货失败，账务状态异常              000258 确认交易失败,确认金额与原交易金额不一致         000215 退货失败，通道失败
000212 退货失败，超出可退货金额            000260 消费撤销发通道扣款超时                         000261 消费退货发通道扣款超时
000199 二维码交易处理中                    000198 二维码交易失败

SDK与DEMO

说明

SDK和DEMO作为参考或示例，请服务商在使用过程中，要专业技术人员指导使用，注意系统兼容性。

Java版本

即将更新。

PHP版本

即将更新。